/*
 * 你的第一个 Orchard Core 控制器 - 基础控制器开发示例
 * 
 * 功能说明：
 * - 演示如何在 Orchard Core 中创建标准的 ASP.NET Core MVC 控制器
 * - 展示 Orchard Core 服务的使用方法（通知器、本地化、日志等）
 * - 提供路由配置和依赖注入的最佳实践示例
 * - 演示本地化、用户通知和日志记录功能
 * 
 * 设计模式：
 * - 依赖注入模式：通过构造函数注入所需服务
 * - 服务定位模式：使用 Orchard Core 的服务容器
 * - 本地化模式：支持多语言文本和 HTML 内容
 * - 通知模式：向用户发送信息、警告和错误消息
 * 
 * 使用场景：
 * - 学习 Orchard Core 控制器开发基础
 * - 理解服务注入和依赖管理
 * - 掌握本地化和用户通知功能
 * - 学习日志记录和错误处理
 */

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Localization;
using Microsoft.Extensions.Localization;
using Microsoft.Extensions.Logging;
using OrchardCore.DisplayManagement.Notify;
using System.Threading.Tasks;

namespace Ruitu.Edu.TrainingDemo.Controllers;

/// <summary>
/// 你的第一个 Orchard Core 控制器 - 基础控制器开发示例
/// 
/// 主要用途：
/// - 演示 Orchard Core 控制器的基本结构和功能
/// - 展示 Orchard Core 核心服务的使用方法
/// - 提供本地化、通知和日志记录的实际示例
/// - 作为学习 Orchard Core 开发的入门示例
/// 
/// 设计模式：
/// - 依赖注入模式：通过构造函数注入所需服务
/// - 服务定位模式：使用 Orchard Core 的服务容器
/// - 本地化模式：支持多语言文本和 HTML 内容
/// - 通知模式：向用户发送信息、警告和错误消息
/// 
/// 学习要点：
/// - 理解 Orchard Core 的 MVC 架构
/// - 掌握服务注入和依赖管理
/// - 学习本地化和用户通知功能
/// - 了解日志记录和错误处理
/// </summary>
public sealed class YourFirstOrchardCoreController : Controller
{
    /// <summary>
    /// 通知器服务 - 用于向用户发送消息
    /// 
    /// 功能说明：
    /// - 提供用户界面消息显示功能
    /// - 支持信息、警告、错误等不同类型的消息
    /// - 可在代码库的几乎所有地方使用，不仅限于控制器
    /// 
    /// 使用场景：
    /// - 操作成功后的用户提示
    /// - 错误信息的用户友好显示
    /// - 系统状态和进度通知
    /// </summary>
    private readonly INotifier _notifier;

    /// <summary>
    /// 字符串本地化器 - 用于文本内容的本地化
    /// 
    /// 功能说明：
    /// - 提供文本内容的本地化支持
    /// - 根据当前文化设置返回相应的本地化文本
    /// - 支持资源文件中的文本键值对
    /// 
    /// 使用场景：
    /// - 界面文本的本地化
    /// - 错误消息的多语言支持
    /// - 动态文本内容的本地化
    /// </summary>
    private readonly IStringLocalizer T;

    /// <summary>
    /// HTML 本地化器 - 用于 HTML 内容的本地化
    /// 
    /// 功能说明：
    /// - 提供 HTML 内容的本地化支持
    /// - 支持包含 HTML 标签的本地化内容
    /// - 与通知器服务配合使用
    /// 
    /// 使用场景：
    /// - 包含 HTML 标签的用户消息
    /// - 富文本内容的本地化
    /// - 通知消息的格式化显示
    /// </summary>
    private readonly IHtmlLocalizer H;

    /// <summary>
    /// 日志记录器 - 用于应用程序日志记录
    /// 
    /// 功能说明：
    /// - 提供应用程序的日志记录功能
    /// - 支持不同级别的日志记录（Debug、Info、Warning、Error 等）
    /// - 在 Orchard Core 中使用 NLog 作为日志提供者
    /// 
    /// 使用场景：
    /// - 应用程序运行状态记录
    /// - 错误和异常的详细记录
    /// - 性能监控和调试信息
    /// 
    /// 注意事项：
    /// - 建议使用泛型版本以确保日志条目包含类名
    /// - 日志文件位置：/App_Data/logs/orchard-log-[date].log
    /// - 可通过 NLog.config 文件配置日志行为
    /// </summary>
    private readonly ILogger _logger;

    /// <summary>
    /// 控制器构造函数 - 演示依赖注入的使用
    /// 
    /// 功能说明：
    /// - 通过构造函数注入所需的 Orchard Core 服务
    /// - 展示依赖注入的最佳实践
    /// - 初始化控制器所需的本地化器和日志记录器
    /// 
    /// 设计模式：
    /// - 依赖注入模式：通过构造函数接收服务实例
    /// - 服务定位模式：使用 Orchard Core 的服务容器
    /// - 接口分离模式：依赖接口而非具体实现
    /// 
    /// 参数说明：
    /// - notifier: 通知器服务，用于用户消息显示
    /// - stringLocalizer: 字符串本地化器，用于文本本地化
    /// - htmlLocalizer: HTML 本地化器，用于 HTML 内容本地化
    /// - logger: 日志记录器，用于应用程序日志记录
    /// 
    /// 学习要点：
    /// - Orchard Core 使用 ASP.NET Core 内置的依赖注入功能
    /// - 可以在模块的 Startup 类中注册自定义服务
    /// - 依赖注入确保代码的可测试性和松耦合
    /// </summary>
    /// <param name="notifier">通知器服务实例</param>
    /// <param name="stringLocalizer">字符串本地化器实例</param>
    /// <param name="htmlLocalizer">HTML 本地化器实例</param>
    /// <param name="logger">日志记录器实例</param>
    public YourFirstOrchardCoreController(
        INotifier notifier,
        IStringLocalizer<YourFirstOrchardCoreController> stringLocalizer,
        IHtmlLocalizer<YourFirstOrchardCoreController> htmlLocalizer,
        ILogger<YourFirstOrchardCoreController> logger)
    {
        _notifier = notifier;
        _logger = logger;

        T = stringLocalizer;
        H = htmlLocalizer;
    }

    /// <summary>
    /// 默认索引操作 - 演示基本的控制器操作
    /// 
    /// 功能说明：
    /// - 返回简单的欢迎消息页面
    /// - 演示本地化文本的使用方法
    /// - 展示基本的 MVC 控制器操作模式
    /// 
    /// 路由信息：
    /// - 默认路由：/Ruitu.Edu.TrainingDemo/YourFirstOrchardCore/Index
    /// - 基于控制器和操作名称的约定路由
    /// 
    /// 使用场景：
    /// - 学习基本的控制器操作编写
    /// - 理解本地化文本的使用
    /// - 掌握 ViewData 的数据传递
    /// 
    /// 学习要点：
    /// - 使用 IStringLocalizer 进行文本本地化
    /// - 通过 ViewData 向视图传递数据
    /// - 理解 Orchard Core 的路由约定
    /// </summary>
    /// <returns>包含本地化消息的视图</returns>
    public ActionResult Index()
    {
        // 使用 IStringLocalizer 服务对简单文本进行本地化
        // 如您所见，可以使用 IStringLocalizer 服务对简单文本进行本地化
        // 要了解 Orchard 中本地化的工作原理，请查看文档：
        // https://docs.orchardcore.net/en/latest/docs/reference/modules/Localize/
        ViewData["Message"] = T["Hello you!"];

        // 视图中没有特殊操作，但您可以在 Views/YourFirstOrchardController/Index.cshtml 文件中查看它
        // Nothing special happens in the view but you can check it in the Views/YourFirstOrchardController/Index.cshtml
        // file.
        return View();
    }

    /// <summary>
    /// 通知操作 - 演示自定义路由和通知功能
    /// 
    /// 功能说明：
    /// - 演示自定义路由配置的使用方法
    /// - 展示日志记录和用户通知功能
    /// - 提供异步操作的最佳实践示例
    /// 
    /// 路由配置：
    /// - 自定义路由：/TrainingDemo/NotifyMe
    /// - 使用 [Route] 特性覆盖默认路由
    /// - 支持 GET 请求方法
    /// 
    /// 功能演示：
    /// - 错误日志记录：演示如何使用 ILogger 记录错误信息
    /// - 用户通知：使用 INotifier 向用户发送信息消息
    /// - 本地化支持：使用 IHtmlLocalizer 进行 HTML 内容本地化
    /// 
    /// 使用场景：
    /// - 学习自定义路由配置
    /// - 理解日志记录和错误处理
    /// - 掌握用户通知功能
    /// - 学习异步操作的最佳实践
    /// 
    /// 学习要点：
    /// - 使用 [Route] 特性配置自定义路由
    /// - 通过 ILogger 记录不同级别的日志信息
    /// - 使用 INotifier 向用户发送友好的消息
    /// - 结合 IHtmlLocalizer 实现本地化通知
    /// </summary>
    /// <returns>通知结果视图</returns>
    [HttpGet, Route("TrainingDemo/NotifyMe")]
    public async Task<IActionResult> NotifyMe()
    {
        // ILogger 是 ASP.NET Core 服务，会将内容写入特定的日志文件
        // 在 Orchard Core 中，NLog 用于日志记录，错误级别默认为 "Error"
        // 您可以在 /App_Data/logs/orchard-log-[date].log 文件中找到错误日志
        // 可以在 Web 项目（例如 OrchardCore.Cms.Web）的 NLog.config 文件中配置日志记录
        // 哦，还有一件事：如果您安装 Lombiq Orchard Visual Studio 扩展，
        // 它会为您提供一个方便的错误日志监视器，如果有新错误，它会亮起！
        // 在这里查看：
        // https://marketplace.visualstudio.com/items?itemName=LombiqVisualStudioExtension.LombiqOrchardVisualStudioExtension
        _logger.LogError("You have been notified about some error!");

        // INotifier 是 Orchard Core 服务，用于向用户发送消息
        // 此服务几乎可以在代码库中的任何地方使用，不仅限于控制器
        // 此服务需要 LocalizedHtmlString 对象，因此需要使用 IHtmlLocalizer 服务进行本地化
        await _notifier.InformationAsync(H["Congratulations! You have been notified! Check the error log too!"]);

        return View();

        // 下一站：Views/YourFirstOrchardCore/NotifyMe.cshtml
    }
}
